<HTML>
<TITLE>module diffusivity</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#CHANGES">CHANGES</A> / 
<A HREF="#ERRORS">ERRORS</A> / 
<A HREF="#REFERENCES">REFERENCES</A> / 
<A HREF="#NOTES">NOTES</A> 
</FONT>
<BR><BR></DIV><HR>


<H2>Module diffusivity_mod</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Steve Klein and Isaac Held
     <B>Reviewers:</B>

     <B><A HREF=".doc.log#diffusivity.f90">Tags/Status</A></B>
</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

     This routine computes the atmospheric vertical diffusivity
     coefficients of momentum and temperature plus tracers at all
     half-levels interior to the atmosphere.   

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>

     The vertical diffusivity coefficients are calculated separately 
     for the planetary boundary layer (PBL) and the free atmosphere. 
     Note that the diffusivity coefficient for temperature is the same 
     as that for all tracers.

     In the PBL, the default prescription of diffusivities is the 
     K-profile boundary layer scheme. A second method is to do the 
     Old Climate Model's version.  In the free atmosphere there
     there are two options, one of which duplicates that used in
     the old Skyhii model.

     A full description can be found <A HREF="diffusivity.tech.ps">here</A>.

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

utilities_mod
constants_mod
monin_obukhov_mod     

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

use diffusivity_mod [,only: diffusivity]

diffusivity -         called every physics time step to compute diffusivity 
                      coefficients.

Notes:

 1) A namelist interface controls runtime options
 2) An initialization routine is called upon the first call to 
    diffusivity.
 2) No restart file is generated by this module.
 3) No other data files are needed.

</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

<b>call diffusivity</b> (t, q, u, v, p_full, p_half, z_full, z_half,
                         u_star, b_star, h, k_m, k_t, kbot)

input:
  
       t     : temperature (K) [real, dimension(:,:,:) -- (:,:,pressure), 
               third index running from top of atmosphere to bottom]

       q     : water vapor specific humidity (nondimensional) 
               [real, dimension(:,:,:)]
                
       u     : zonal wind (m/s) [real, dimension(:,:)]

       v     : meridional wind (m/s) [real, dimension(:,:,:)] 

       p_full : pressure at full levels (pascals)

       p_half : pressure at half levels (pascals)

       z_full : height of full levels (m)
                [real, dimension(:,:,:), size(z_full,3) = size(t,3)]

       z_half : height of  half levels (m)
                [real, dimension(:,:,:), size(z_half,3) = size(t,3) +1
                z_half(:,:,size(z_half,3)) must be height of surface 
                (for non-eta models)!]

       u_star: friction velocity (m/s)
               [real, dimension(:,:)]
               
       b_star: buoyancy scale (m/s**2)
               [real, dimension(:,:)]
               
                   surface stress = ustar*ustar
                   surface buoyancy flux = ustar*bstar 
                      bstar > 0 => upward flux

                 (u_star and b_star are output from  
                  mo_drag in monin_obukhov_mod
                  along with the drag_coeffcients )


output: 

         h     : pbl depth (meters) [real, dimension(:,:)]
    
       k_m     : momentum diffusivity coefficient ((meters)**2./second)
                 [real, dimension(:,:,:)]

       k_t     : temperature, vapor and scalars diffusivity coefficient 
                 ((meters)**2./second)
                 [real, dimension(:,:,:)]

                defined at half-levels
                size(k_m and k_t,3) should be at least as large as size(t,3)
                only the returned values at 
                      levels 2 to size(t,3) are meaningful
                other values will be returned as zero
                That is k_m(:,:,2) is the diffusivity coefficient
                between full model levels 1 and 2. (Full model level 1
                is the top level of the model.)

optional input:

       kbot    : lowest true model level (for use with eta grid point model)
                 [integer, dimension(:,:)]



</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&diffusivity_nml</b>

fixed_depth         should the boundary layer depth be fixed?
                    [logical, default: fixed_depth = .false.]

depth_0             height of fixed depth boundary (meters)
                    [real, default: depth_0 = 5000.]

frac_inner          height of the surface layer as a fraction of
                    the boundary layer depth
                    [real, default: frac_inner = 0.1]

rich_crit_pbl       critical richardson number used to compute 
                    boundary layer depth in the neutral or stable
                    case
                    [real, default: rich_crit_pbl = 1.0]

entr_ratio          ratio of entrainment buoyancy flux to surface
                    buoyancy flux (must be >= 0.)
                    [real, default: entr_ratio = 0.2]

parcel_buoy         scaling factor for the excess buoyancy of the
                    parcel used to determine the boundary layer
                    depth in the unstable case
                    [real, default: parcel_buoy = 2.]

znom                nominal boundary layer depth used only in the
                    calculation of surface layer vertical velocity
                    scale.  this velocity scale is used only in
                    the calculation of parcel buoyancy in the unstable
                    case (meters)
                    [real, default: znom = 1000.]

free_atm_diff       should there be richardson number dependent
                    mixing in the free atmosphere?
                    [logical, default: free_atm_diff = .false.]

free_atm_skyhi_diff should the free atmospheric diffusion
                    depend on model level thickness and the 
                    prandtl number depend on the richardson number
                    (as in the formulation previously used in skyhi)?
                    [logical, default: free_atm_skyhi_diff = .false.]

pbl_mcm             When .true., the pbl K profile is that of the Manabe Climate Model.
                    [logical, default: pbl_mcm = .false.]

rich_crit_diff      critical richardson number beneath which free
                    atmospheric diffusion occurs
                    [real, default: rich_crit_diff = 0.25 ] 

mix_len             mixing length used in free atmospheric diffusion
                    (meters)
                    [real, default: mix_len = 30.]

rich_prandtl        Prandtl number used in the scaling of k_m to
                    k_t in the free atmospheric diffusion 
                    [real, default: rich_prandtl = 1.]

background_m        background value of K for momentum (m**2/sec)
                    [real, default: background_m = 0.]

background_t        background value of K for temperature and tracers
                    (m**2/sec)
                    [real, default: background_t = 0.]

Notes:  (1) To get Climate Model's PBL diffusivities set
            pbl_mcm to TRUE, fixed_depth to TRUE, 
            depth_0 to 5000. and frac_inner to 0.015.

        (2) To get K-profile diffusivities, pbl_mcm
            must be FALSE (default) and fixed_depth must be 
            FALSE (default).

        (3) To have any vertical diffusion in the free atmosphere
            free_atm_diff must be set to TRUE.

        (4) To get skyhi free atmospheric diffusivities, both
            free_atm_skyhi_diff and free_atm_diff must be set
            to true.

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>
<B><A HREF=".doc.log#diffusivity.f90">Revision history</A></B>

<b>changes</b> (10/4/1999)

     MPP version created. Minor changes in open_file, error_mesg,
     and Fortran write statements. Answers should reproduce the
     previous version.

<b>changes</b> (8/16/1999)

     Code to set background diffusivities is moved out of
     diffusivity_free subroutine and into the diffusivity subroutine
     so that it is possible to set a background level of diffusivity
     even if free_atm_diff = FALSE.  
     (This was impossible in previous revisions).

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

diffusivity_init:

     namelist parameters are checked to see if valid selections
     have been made.  The following settings are prohibited and
     the model will shut down if any are chosen:

     (1) frac_inner <= 0 or frac_inner >= 1.
     (2) rich_crit_pbl < 0.
     (3) entr_ratio < 0.
     (4) znom < 0.
     (5) free_atm_skyhi_diff = TRUE and free_atm_diff = FALSE
     (6) rich_crit_diff <= 0.
     (7) mix_len < 0.
     (8) rich_prandtl < 0.
     (9) background_m < 0.
     (10) background_t < 0.

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="REFERENCES">
<HR>
<H4>REFERENCES</H4>
<!-- BEGIN REFERENCES -->
<PRE>

     See <A HREF="diffusivity.tech.ps">technical documention</A>.

</PRE>
</A><!-- END REFERENCES -->
<!--------------------------------------------------------------------->
<A NAME="NOTES">
<HR>
<H4>NOTES</H4>
<!-- BEGIN NOTES -->
<PRE>

    None.

</PRE>
</A><!-- END NOTES -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

    None.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
